home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat2 / standard / sysget.z / sysget
Encoding:
Text File  |  2002-10-03  |  9.2 KB  |  265 lines
  1.  
  2.  
  3.  
  4. SSSSYYYYSSSSGGGGEEEETTTT((((2222))))                                                            SSSSYYYYSSSSGGGGEEEETTTT((((2222))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      sysget - Call for reading or writing kernel data
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      #include <sys/sysget.h>
  13.  
  14.      sysget (int name, char *buffer, int buflen, int flags,
  15.      sgt_cookie_t *cookie);
  16.  
  17. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  18.      The sysget system call provides user access to kernel structures and
  19.      tables on IRIX systems. sysget can return data for a combination of cpus,
  20.      nodes, or cells depending on the combination of flags and cookie
  21.      settings.
  22.  
  23.      The sysget system call accepts the following arguments:
  24.  
  25.      name    Identifies the kernel structure or table. The sys/sysget.h file
  26.              contains the list of names supported. Most come from the sysmp
  27.              MP_SAGET options.  Here is a partial list:
  28.  
  29.              SGT_SINFO    SGT_MINFO SGT_DINFO SGT_SERR Returns the various
  30.                           sysinfo-type structures. See the sys/sysinfo.h file.
  31.  
  32.              SGT_RMINFO   Returns the rminfo structure. See the sys/sysmp.h
  33.                           file.
  34.  
  35.              SGT_RMINFO64 Returns the 64 bit version of the rminfo structure.
  36.                           This interface was added in IRIX 6.5.17 to support
  37.                           larger memory models.  See the sys/sysmp.h file.
  38.  
  39.              SGT_NODE_INFO
  40.                           Returns the nodeinfo structure for each node. See
  41.                           the sys/sysinfo.h file.
  42.  
  43.              SGT_NODE_INFO64
  44.                           Returns the nodeinfo structure for each node. This
  45.                           interface will allow for the larger values of memory
  46.                           per node on some machines. Added in IRIX 6.5.16.
  47.                           See the sys/sysinfo.h file.
  48.  
  49.              SGT_KSYM     Returns the structure identified by the kernel
  50.                           symbol specified in the cookie by using the
  51.                           SGT_COOKIE_SET_KSYM() macro. Only a subset of kernel
  52.                           symbols are supported. See the sys/sysget.h file.
  53.  
  54.      buffer  Points to the user's buffer space.
  55.  
  56.      buflen  Specifies the size of buffer in bytes.
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. SSSSYYYYSSSSGGGGEEEETTTT((((2222))))                                                            SSSSYYYYSSSSGGGGEEEETTTT((((2222))))
  71.  
  72.  
  73.  
  74.      flags   Specifies option flags.  A user must select the SGT_INFO,
  75.              SGT_READ, or SGT_WRITE flag.  flags is combination of one or more
  76.              of the following:
  77.  
  78.              SGT_INFO     Returns information on the kernel structure or table
  79.                           defined by the name argument. This option is similar
  80.                           to the sysmp MP_SASZ option.  The buffer argument
  81.                           points to a structure defined in the sys/sysget.h
  82.                           file as the following:
  83.  
  84.                            struct sgt_info {
  85.                                  int      si_size;
  86.                                  int      si_num;
  87.                                  int      si_hiwater;
  88.                            }
  89.  
  90.              SGT_READ     Returns the information defined by the name argument
  91.                           in the buffer specified by the buffer argument.
  92.  
  93.              SGT_STAT     Returns information about the table or server
  94.                           specified by the name argument. This information is
  95.                           similar to that provided by the SGT_INFO flag.
  96.  
  97.              SGT_SUM      This flag is obsolete and will be ignored.
  98.  
  99.              SGT_WRITE    Writes the information specified by the buffer
  100.                           argument to the kernel structure defined by the name
  101.                           argument.
  102.  
  103.              SGT_CPUS     Returns data for each cpu. Not all structures
  104.                           support this option.
  105.  
  106.              SGT_NODES    Returns data for each node. Not all structures
  107.                           support this option.
  108.  
  109.      cookie  Specifies which cell, cpu, or node should be used when asking for
  110.              information.  The kernel also uses it as a place-holder mechanism
  111.              to allow sysget to be used iteratively to return a list of
  112.              structures when the length of the list is unknown. Other uses are
  113.              to specify a specific location to seek to in a list.
  114.  
  115.              This argument points to a structure defined as follows:
  116.  
  117.               struct sgt_cookie {
  118.                      sc_status_t    sc_status;
  119.                      union {
  120.                              cell_t          cellid;
  121.                              cnodeid_t       cnodeid;
  122.                              int             cpuid;
  123.                      } sc_id;
  124.                      sc_type_t       sc_type;
  125.                      char            sc_opaque[SGT_OPAQUE_SZ];
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. SSSSYYYYSSSSGGGGEEEETTTT((((2222))))                                                            SSSSYYYYSSSSGGGGEEEETTTT((((2222))))
  137.  
  138.  
  139.  
  140.               }
  141.  
  142.              The cookie must be initialized before the first call by using the
  143.              SGT_COOKIE_INIT() macro.  See the sys/sysget.h file
  144.  
  145. RRRREEEETTTTUUUURRRRNNNN VVVVAAAALLLLUUUUEEEESSSS
  146.      If sysget completes normally, the number of bytes copied is returned,
  147.      otherwise a value of -1 is returned and errno is set to indicate the
  148.      error.
  149.  
  150. EEEERRRRRRRROOOORRRRSSSS
  151.      The sysget system call fails if one of the following error conditions
  152.      occurs:
  153.  
  154.      EEEErrrrrrrroooorrrr CCCCooooddddeeee          DDDDeeeessssccccrrrriiiippppttttiiiioooonnnn
  155.  
  156.      EFAULT              The buffer address specified is not valid.
  157.  
  158.      EINVAL              A flag was specified in a context that was not valid
  159.                          or the cookie was not set properly.
  160.  
  161.      ENOENT              The value specified in the name argument or in
  162.                          combination with the cookie is unknown.
  163.  
  164.      ENOTSUP             The function specified by the flags parameter is not
  165.                          supported.
  166.  
  167.      ESRCH               The cookie or cpu specified is not valid.
  168.  
  169.      EOVERFLOW           The function specified has at least one field in the
  170.                          return structure that overflowed.
  171.  
  172. EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS
  173.      The following examples show how to use the sysget system call to retrieve
  174.      information.
  175.  
  176.      Example 1:  This example shows how to use sysget to obtain the number and
  177.      size of sysinfo structures in the system (a system running cells will
  178.      have a sysinfo structure per cell):
  179.  
  180.         sgt_info_t info;
  181.         sgt_cookie_t cookie;
  182.  
  183.         SGT_COOKIE_INIT(&cookie);
  184.         sysget(SGT_SINFO, (char *)&info, sizeof(info),
  185.                 SGT_INFO, &cookie);
  186.         printf("number of sysinfo: %d, size: %d\n",
  187.                 info.si_num, info.si_size);
  188.  
  189.      Example 2:  In this example, sysget reads the list of sysinfo structures
  190.      for each cpu:
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. SSSSYYYYSSSSGGGGEEEETTTT((((2222))))                                                            SSSSYYYYSSSSGGGGEEEETTTT((((2222))))
  203.  
  204.  
  205.  
  206.         sgt_info_t info;
  207.         sgt_cookie_t cookie;
  208.         struct sysinfo *si;
  209.  
  210.         SGT_COOKIE_INIT(&cookie);
  211.         sysget(SGT_SINFO, (char *)&info, sizeof(info),
  212.                 SGT_INFO | SGT_CPUS, &cookie);
  213.  
  214.         si = (struct sysinfo *)malloc(info.si_num * info.si_size);
  215.  
  216.         SGT_COOKIE_INIT(&cookie);
  217.         sysget(SGT_SINFO, (char *)si, info.si_num * info.si_size,
  218.                 SGT_READ | SGT_CPUS, &cookie);
  219.  
  220.      Example 3:  In this example, sysget reads the list of sysinfo structures
  221.      for each cpu one at a time by iterating on the cookie:
  222.  
  223.         sgt_info_t info;
  224.         sgt_cookie_t cookie;
  225.         struct sysinfo si;
  226.  
  227.         SGT_COOKIE_INIT(&cookie);
  228.         while (cookie.sc_status != SC_DONE) {
  229.                sysget(SGT_SINFO, (char *)&si, sizeof(si),
  230.                    SGT_READ | SGT_CPUS, &cookie);
  231.         }
  232.  
  233.      Example 4:  This example shows how to use sysget to read the contents of
  234.      a structure by specifying its kernel symbol using the SGT_KSYM option:
  235.  
  236.         sgt_cookie_t cookie;
  237.         int avenrun[3];
  238.  
  239.         SGT_COOKIE_INIT(&cookie);
  240.         SGT_COOKIE_SET_KSYM(&cookie, "avenrun");
  241.         sysget(SGT_KSYM, (char *)avenrun, sizeof(avenrun),
  242.                 SGT_READ, &cookie);
  243.  
  244. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  245.      sysmp(2), syssgi(2), nlist(3C), sysctl(3C)
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.